SETMEM Function
 ----------------------------------------------------------------------------


 Action

 Changes the amount of memory used by the far heap -- the area where far
 objects are stored -- and returns information about the far heap.


 Syntax



  SETMEM( numeric- expression&)

 Remarks


 The   SETMEM function increases or decreases the far heap by the number of
 bytes indicated by  numeric- expression&. If  numeric-expression& is
 negative,  SETMEM decreases the far heap by the indicated number of bytes.
 If  numeric-expression& is positive,  SETMEM attempts to increase the far
 heap by the number of bytes. If  SETMEM cannot change the far heap by the
 requested number of bytes, it reallocates as many bytes as possible.

  SETMEM can be used in mixed-language programming to decrease the far heap
 so procedures in other languages can dynamically allocate far memory.

 The information that the  SETMEM function returns about the far heap depends
 on the value of  numeric-expression&, as follows.

-----------------------------------------------------------------------------
 ----------------------------------------------------------------------------
 Positive or negative      Total number of bytes in the far heap.
 0                         Current size of far heap.





 Note

 A first call to  SETMEM trying to increase the far heap has no effect
 because BASIC allocates as much memory as possible to the far heap when a
 program starts.

 When programming with OS-2 protected mode, the  SETMEM function performs no
 other function than to return a dummy value. This value is the previous
 SETMEM value adjusted by the  SETMEM argument. The initial value for  SETMEM
 is 655,360.


 Example


 In the following example,  SETMEM is used to free memory for a C routine
 that uses the C function malloc to get dynamic memory. The C routine must be
 separately compiled and then put in a Quick library or linked to the BASIC
 program.

 DECLARE SUB CFunc CDECL (BYVAL X AS INTEGER)





 ' Decrease the size of the far heap so CFunc can use


 ' malloc to get dynamic memory.


 BeforeCall = SETMEM(-2048)





 CFunc(1024%)' Call the C routine.





 ' Return the memory to the far heap; use a larger value so


 ' all space goes back into the heap.


 AfterCall = SETMEM(3500)


 IF AfterCall <= BeforeCall THEN PRINT "Memory not reallocated."


 END




 This routine is compiled using the large memory model, so calls to the C
 function malloc use the far space freed by the BASIC program.


 void far cfunc(bytes)


 int bytes;


 {


    char *malloc();


    char *workspace;





    -* Allocate working memory using amount BASIC freed. *-


    workspace=malloc((unsigned) bytes);





    -* Working space would be used here. *-





    -* Free memory before returning to BASIC. *-


    free(workspace);


 }